import { NotificationDemos, NotificationsDemos } from '@docs/demos';
import { Layout } from '@/layout';
import { MDX_DATA } from '@/mdx';

export default Layout(MDX_DATA.Notifications);

## Installation

<InstallScript packages="@mantine/notifications" />

After installation import package styles at the root of your application:

```tsx
import '@mantine/core/styles.css';
// ‼️ import notifications styles after core package styles
import '@mantine/notifications/styles.css';
```

Add `Notifications` component anywhere in your application. Note that:

- It is required to render `Notifications` component inside [MantineProvider](/theming/mantine-provider/)
- You do not need to wrap your application with `Notifications` component – it is not a provider, it is a regular component
- You should not render multiple `Notifications` components – if you do that, your notifications will be duplicated

```tsx
import { MantineProvider } from '@mantine/core';
import { Notifications } from '@mantine/notifications';

function Demo() {
  return (
    <MantineProvider>
      <Notifications />
      {/* Your app here */}
    </MantineProvider>
  );
}
```

All set! You can now use all notifications system features.

<Demo data={NotificationsDemos.base} />

## Do not forget to import styles

Followed installation instructions above but something is not working
(`position` prop not working, notifications are stuck at the bottom)?
You've fallen into the trap of not importing notifications styles!
To fix the issue, import notifications styles at the root of your application:

```tsx
import '@mantine/notifications/styles.css';
```

## Functions

`@mantine/notifications` package exports `notifications` object with the following functions:

- `notifications.show` – adds given notification to the notifications list or queue, depending on the current state and `limit`
- `notifications.hide` – removes notification with given `id` from the notifications state and queue
- `notifications.update` – updates notification that was previously added to the state or queue
- `notifications.updateState` – executes given callback with current notifications state and queue as an argument and updates state with returned value
- `notifications.clean` – removes all notifications from the notifications state and queue
- `notifications.cleanQueue` – removes all notifications from the queue

All functions can be imported from `@mantine/notifications` package and can be used in any part of your application:

```tsx
import { notifications } from '@mantine/notifications';
```

You can also import these functions separately:

```tsx
// alias functions
import {
  cleanNotifications, // notifications.clean
  cleanNotificationsQueue, // notifications.cleanQueue
  hideNotification, // notifications.hide
  showNotification, // notifications.show
  updateNotification, // notifications.update
  updateNotificationsState, // notifications.updateState
} from '@mantine/notifications';
```

## Notification props

`notifications.show` and `notification.update` functions can be called with an object that has the following properties:

- `id` – notification id, it is used to update and remove notifications, by default `id` is randomly generated
- `position` – notification position, by default the value from the `position` prop of the `Notifications` component is used
- `withBorder` – determines whether notification should have a border
- `withCloseButton` – determines whether the close button should be visible
- `onClose` – calls when notification is unmounted
- `onOpen` – calls when notification is mounted
- `autoClose` – defines timeout in ms on which notification will be automatically closed, use `false` to disable auto close
- `message` – required notification body
- `color, icon, title, radius, className, style, loading` – props passed down to the [Notification](/core/notification/) component

All properties except `message` are optional.

```tsx
import { IconX } from '@tabler/icons-react';
import { notifications } from '@mantine/notifications';

// Bare minimum – message is required for all notifications
notifications.show({ message: 'Hello' });

// Most used notification props
notifications.show({
  id: 'hello-there',
  position: 'bottom-center',
  withCloseButton: true,
  onClose: () => console.log('unmounted'),
  onOpen: () => console.log('mounted'),
  autoClose: 5000,
  title: "You've been compromised",
  message: 'Leave the building immediately',
  color: 'red',
  icon: <IconX />,
  className: 'my-notification-class',
  style: { backgroundColor: 'red' },
  loading: false,
});
```

Notifications preview (`message` prop used as `children`):

<Demo
  data={NotificationDemos.configurator}
  configuratorProps={{ includeCode: false }}
/>

## Customize notification styles

You can use `style`, `className` or [Styles API](/styles/styles-api/) `classNames`, `styles` props to customize notification styles.
Usually, it is better to override [Notification](/core/notification) styles with `classNames` prop in the [theme object](/theming/theme-object/).

<Demo data={NotificationsDemos.customize} />

## Notifications container position

You can define notification position in `notifications.show` function. Possible `position` values:

- `top-left`
- `top-right`
- `top-center`
- `bottom-left`
- `bottom-right`
- `bottom-center`

<Demo data={NotificationsDemos.position} />

The `position` can be defined on the `Notifications` component.
In the following example, notifications will be displayed in the top right corner of the screen
if `position` is not defined in `notifications.show` function:

```tsx
import { Notifications } from '@mantine/notifications';

function Demo() {
  return <Notifications position="top-right" zIndex={1000} />;
}
```

## Limit and queue

You can limit maximum number of notifications that are displayed at a time by setting
`limit` prop on `Notifications`:

```tsx
import { Notifications } from '@mantine/notifications';

function Demo() {
  return <Notifications limit={5} />;
}
```

All notifications added after the `limit` was reached are added to the queue
and displayed when notification from current state is hidden.

<Demo data={NotificationsDemos.limit} />

## Remove notifications from state and queue

To remove specific notification from state or queue use `notifications.hide` function:

```tsx
import { notifications } from '@mantine/notifications';

const id = notifications.show({ message: 'Hello!' });
notifications.hide(id);
```

Use `notifications.cleanQueue` function to remove all notifications from the queue and
`notifications.clean` to remove all notifications both from the state and queue:

<Demo data={NotificationsDemos.clean} />

## Update notification

<Demo data={NotificationsDemos.update} />

## Auto close

You can configure auto close timeout with `Notifications`:

```tsx
import { Notifications } from '@mantine/notifications';

// All notifications will be closed automatically in 4000ms
function Demo() {
  return <Notifications autoClose={4000} />;
}
```

Or per notification in `notifications.show`/`notifications.update` functions:

```tsx
import { notifications } from '@mantine/notifications';

notifications.show({
  message: 'I will close in 500ms seconds',
  autoClose: 500,
});

notifications.update({
  id: 'hello',
  message: 'I will never close',
  autoClose: false,
});
```

`notifications.show` and `notifications.update` functions `autoClose` prop has higher priority.

<Demo data={NotificationsDemos.autoclose} />

## Subscribe to notifications state

You can subscribe to notifications state changes with `useNotifications` hook.
The hook returns an object with `notifications` and `queue` arrays. `notifications`
array contains all notifications that are currently displayed, `queue` contains
notifications that are waiting to be displayed.

<Demo data={NotificationsDemos.store} />
